|
|
Table of Contents
NOTE: you can find this and other lessons in a
more complete and viewable format (including all Figures) in our Tutorial PDF.
Lesson 7. How to Create Your Own Fields
-
This lesson teaches you how to create your own fields to use in a report. The control statement discussed is:
-
the
COMPUTE
statement
-
Sometimes the data you need for a report is not in the SMF record. Yet the data might be easily computed from one or more fields which are in the record. In such cases, simply create a new field with a
COMPUTE
statement.
Creating Numeric Fields
-
A
COMPUTE
statement specifies the name of a new field to create and supplies a computational expression to assign a value to that field. The complete rules for computational expressions are discussed in . Basically, your expression will consist of one or more arithmetic operations performed with SMF fields and/or literals.
-
For example, refer back to the report in Figure _. That report has two numeric columns -- the EXCP block count (
SMF30BLK
) and the maximum block size (
SMF30BSZ
). We could compute our own new field called "maximum EXCP bytes" by multiplying those two fields together:
COMPUTE: MAX-EXCP-BYTES = SMF30BLK * SMF30BSZ
-
Now that the
MAX-EXCP-BYTES
field has been created, we can use that field in any way that other fields can be used. For example, a computed field can be used: as a column in the body of the report; in the report titles; as a sort field; as a control break field; as part of a conditional expression (in the
INCLUDEIF
statement); or even as an operand in a subsequent
COMPUTE
statement to create another field.
-
Figure _ shows a report that uses the above
COMPUTE
statement.
Computing your own fields for a report
Computing your own fields for a report
+
|
-
You can perform addition, subtraction, multiplication, and division in the
COMPUTE
statement. Use the +, -, * and / symbols, respectively. You may also use parentheses as needed to indicate the order in which the operations should be performed.
-
since dashes are allowed as characters in field names, when performing subtraction, always put a blank space before and after the minus sign. Otherwise, the minus sign will be treated as part of the field name. Blanks are optional around the other arithmetic operators.
-
In addition to these arithmetic operations, there are also a large number of built-in functions that you can use in the
COMPUTE
statement. These built-in functions allow you to perform more complex operations on SMF data. A complete list of built-in functions is found in .
-
-
COMPUTE
statements usually come after the
INPUT
statement, so that you can refer to fields from the input file. And your
COMPUTE
statement must appear before any control statement that uses the field being created. Beyond that, the precise location of a
COMPUTE
statement is not important. The contents of a
COMPUTE
field is calculated once for each new record from the input file.
Technical Discussion: When is the Computation Actually Performed?
-
(Feel free to skip over this section if you like.) Since Spectrum SMF Writer's language is non-procedural, the exact location of a
COMPUTE
statement does not affect when, or even whether, the computation is actually performed for a given input record.
-
For efficiency's sake, Spectrum SMF Writer performs computations only if or when the value of the field is actually needed. In that sense, the
COMPUTE
statement is similar to the
FIELD
statement. Both statements describe how to obtain the contents of a given field. (The
FIELD
statement tells where the raw data is located in the input record, and what format it is in; the
COMPUTE
statement tells what formula to use to calculate the value of a field.) But Spectrum SMF Writer itself decides when and whether it actually needs to go to the effort of obtaining a field's value while producing the report.
-
For example, assume that a
COMPUTE
field is used in the
COLUMNS
statement, but is not referred to in the
INCLUDEIF
statement. If the
INCLUDEIF
statement fails for an input record, Spectrum SMF Writer will not need to calculate the
COMPUTE
field's value at all for that record. It only needs to compute the value if the record passes the
INCLUDEIF
statement's conditions (so that the data can be shown in the output line).
-
For this reason, it is fine to store commonly used
COMPUTE
statements right in the copy library along with a file definition. They will not add any (significant) overhead to report runs that do not actually use them.
Creating Time Fields
-
When working with SMF files, time data plays an important role. You can calculate useful information from the time stamps (and time intervals) contained in many SMF records.
-
For example, the SMF 30 record has two CPU time fields named
SMF30UCT
(total TCB time) and
SMF30UCS
(total SRB time). We can use a
COMPUTE
statement to create a new CPU time field containing the combined SRB and TCB time. We just add the two time fields together, like this:
COMPUTE: TOTAL-CPU-TIME = SMF30UCT + SMF30UCS
-
The report in Figure _ uses the above statement.
-
The
TOTAL-CPU-TIME
field created in this statement is a time field. So by default it is formatted in the report as
HH:MM:SS.DD
. If you find that you are dealing with very small time intervals, (like the 00:00:00.24 in Figure _, you may prefer to view the data as a numeric number of seconds. Use the
#MAKENUM
built-in function to change the value from a time field to a numeric field.
COMPUTE: CPU-SECONDS = #MAKENUM(TOTAL-CPU-TIME)
-
When times are converted to numeric values, the result is the total number of seconds contained in the time field. The report in now shows this computed field as a numeric value (0.24).
Calculating Elapsed Times
-
Let's look at another example of computing time fields. When working with SMF data, it is often useful to calculate the time difference between two time fields. Let's say that we want to show a job's total elapsed run time. There is no field in the SMF 30 record that contains the elapsed time. However, we can compute it by calculating the difference between two time-of-day fields that are present in SMF 30 (subtype 5) records.
SMF30SIT
is the time of day that the initiator selected the job. And
SMF30TME
is the time that SMF logged the termination of the job.
-
So it might seem tempting to just compute the elapsed time like this
COMPUTE: JOB-ELAPSED-TIME = SMF30TME - SMF30SIT
-
However, this simple method has an obvious drawback. It won't work if the job runs past midnight and ends on the next day. (The time difference will be negative). The correct way to compute this elapsed time is to also take into account the dates when the job began and ended. The job initiation date is in
SMF30STD
. And the SMF log date is in
SMF30DTE
. Now armed with these four fields, Spectrum SMF Writer's powerful built-in functions make the calculation easy:
COMPUTE: JOB-ELAPSED-SECONDS =
(#MAKENUM(SMF30DTE) * 86400 + #MAKENUM(SMF30TME))
- (#MAKENUM(SMF30STD) * 86400 + #MAKENUM(SMF30SIT))
-
The statement above creates a field that contains the number of elapsed seconds that a job ran. (It does this by converting both the start date/time and the end date/time into their total number of seconds since the beginning of the nineteenth century, and then subtracting the starting value from the ending value.) Figure _ in the next chapter Figure _ shows a report that uses this
COMPUTE
statement.
-
If you prefer to see the elapsed time in regular
HH:MM:SS
time format, you can convert this numeric seconds field to a time field, like this:
COMPUTE: JOB-ELAPSED-TIME = #MAKETIME(JOB-ELAPSED-SECONDS)
-
Figure _ also shows this computed field.
Creating Character Fields
-
You can also create character fields. There is only one operation used in computing character fields -- the concatenation operation. The plus sign (+) is used as the symbol for concatenation. Of course, there are also many built-in functions that operate on and/or return character data.
-
Here is an example of a character field that is handy for reports from many SMF record types, including type 14.
COMPUTE: SMF14-JOBID = SMF14JBN
+ ' ' + #FORMAT(SMF14RSD)
+ ' ' + #FORMAT(SMF14RST)
-
The above statement creates a single new field that has a unique value for every job in the SMF file. It concatenates the jobname with the date and time that the job hit the internal reader. This combination forms a unique identifier for the job, And this is very useful when you want to sort and break on all of the records for a single job -- perhaps printing a total line for the job. In fact, there is an example of using this field in just that way in Figure _.
-
In the statement above, we used the
#FORMAT
built-in field in two places. This is necessary because you can only concatenate character fields. The
#FORMAT
function formats the date value in
SMF14RSD
into a
MM/DD/YY
character field. Similarly, we formatted the
SMF30RST
time field into a
HH:MM:SS.DD
character field.
-
We also inserted blanks between these SMF fields to make the result more readable, in case we want to print it in the report.
-
Here is one more example of using built-in fields to easily extract data that would take quite a few steps in a procedural language. We use the
#REPLACE
and
#PARSE
functions to extract just the first node of the
DSNAME
field from the SMF 14 record.
COMPUTE: FIRST-NODE = #PARSE(#REPLACE(SMF14_JFCBDSNM, '.', ' '), 1)
Summary
-
Here is a summary of what we learned in this lesson:
-
the
COMPUTE
statement is used to create new fields
-
a simple
COMPUTE
statement assigns the result of a single computational expression to a new field
-
The next lesson will introduce a more complex form of the
COMPUTE
statement.
To Learn More
-
You can also learn:
-
about many powerful built-in functions available in the
COMPUTE
statement, listed in
-
how to specify the number of decimal places a numeric or time field should contain ()
-
the complete syntax for the
COMPUTE
statement, in .
|
